{"id":25256557,"url":"https://github.com/puzzlet-ai/agentmark","last_synced_at":"2025-04-05T17:02:37.872Z","repository":{"id":259646150,"uuid":"873695975","full_name":"puzzlet-ai/agentmark","owner":"puzzlet-ai","description":"Markdown for the AI era","archived":false,"fork":false,"pushed_at":"2025-03-29T01:11:46.000Z","size":16441,"stargazers_count":139,"open_issues_count":7,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T01:32:57.663Z","etag":null,"topics":["agents","llms","observability","opentelemetry","prompt","prompt-engineering","prompt-management"],"latest_commit_sha":null,"homepage":"https://docs.puzzlet.ai/agentmark/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puzzlet-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-16T15:06:49.000Z","updated_at":"2025-03-29T01:11:47.000Z","dependencies_parsed_at":"2024-11-15T15:26:16.331Z","dependency_job_id":"5427ea61-b24a-4ab1-a7f2-580faabf2810","html_url":"https://github.com/puzzlet-ai/agentmark","commit_stats":null,"previous_names":["puzzlet-ai/promptdx","puzzlet-ai/agentmark"],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzzlet-ai%2Fagentmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzzlet-ai%2Fagentmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzzlet-ai%2Fagentmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzzlet-ai%2Fagentmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puzzlet-ai","download_url":"https://codeload.github.com/puzzlet-ai/agentmark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369948,"owners_count":20927927,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","llms","observability","opentelemetry","prompt","prompt-engineering","prompt-management"],"created_at":"2025-02-12T06:20:18.423Z","updated_at":"2025-04-05T17:02:37.836Z","avatar_url":"https://github.com/puzzlet-ai.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003eAgentMark\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/puzzlet-ai\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://i.imgur.com/xwq74He.png\"\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://i.imgur.com/JN9seOy.png\"\u003e\n      \u003cimg src=\"https://i.imgur.com/xwq74He.png\" alt=\"AgentMark Logo\" width=\"200\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMarkdown for the AI Era\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/P2NeMDtXar\"\u003eDiscord\u003c/a\u003e |\n  \u003ca href=\"https://docs.puzzlet.ai/agentmark/\"\u003eDocs\u003c/a\u003e |\n  \u003ca href=\"https://puzzlet.ai\"\u003ePuzzlet\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\nDevelop type-safe prompts and agents using readable Markdown and JSX.\n\n### Features\n\nAgentMark supports:\n\n1. Markdown: 📝\n1. Type Safety: 🛡️\n1. Unified model config: 🔗\n1. JSX components, props, \u0026 plugins: 🧩\n1. Loops, Conditionals, and Filter Functions: ♻️\n1. Custom SDK Adapters: 🛠️\n1. JSON Output: 📦\n1. Tools \u0026 Agents: 🕵️\n1. Text, Object, and Image output. Audio/Video coming soon.\n\nRead our [docs](https://docs.puzzlet.ai/agentmark/) to learn more.\n\n## Getting Started\n\nBelow is a basic example to help you get started with AgentMark:\n\n`example.prompt.mdx`\n```mdx\n---\nname: basic-prompt\nmodel:\n  name: gpt-4o-mini\ntest_settings:\n  props:\n    num: 3\n---\n\n\u003cSystem\u003eYou are a math expert\u003c/System\u003e\n\n\u003cUser\u003eWhat's 2 + {props.num}?\u003c/User\u003e\n```\n\n## Models\n\nBy default, AgentMark doesn't support any models or calling any LLM providers. Instead, we format the input of your prompt through an adapter to match the input of the SDK you're using.\n\n### Supported Adapters\n\n| Adapter   | Supported | Supports Type-Safety |\n|-----------|-----------|-----------|\n| Default   | ✅ | ✅ |\n| Custom    | ✅ | ✅ |\n| Vercel (Recommended)  | ✅ | ✅ |\n| Mastra    | ⚠️ Coming Soon | ⚠️ |\n| LangChain  | ⚠️ Coming Soon | ❌ |\n| OpenAI Compatible    | ⚠️ Coming Soon | ❌ |\n\nWant to add support for another adapter? Open an [issue](https://github.com/puzzlet-ai/agentmark/issues).\n\n### Supported Prompt Types\n\n| Prompt Type   | Supported |\n|-----------|-----------|\n| Object    | ✅ |\n| Text    | ✅ |\n| Image    | ✅ |\n| Audio    | ⚠️ Coming Soon |\n| Video    | ⚠️ Coming Soon |\n\n### Custom Adapters\n\nRefer to our [docs](https://docs.puzzlet.ai/agentmark/) to learn how to add custom adapter support.\n\n## Language Support\n\nWe plan on providing support for AgentMark across a variety of languages.\n\n| Language | Support Status |\n|----------|---------------|\n| TypeScript | ✅ Supported |\n| JavaScript | ✅ Supported |\n| Python | ⚠️ Coming Soon |\n| Others | Need something else? [Open an issue](https://github.com/puzzlet-ai/agentmark/issues) |\n\n## Running AgentMark\n\nYou can run AgentMark using any of the following methods:\n\n### 1. VSCode Extension\n\nRun .prompt.mdx files directly within your VSCode editor. Note: You can test props by using `test_settings` in your prompts.\n\n[Download the VSCode Extension](https://marketplace.visualstudio.com/items?itemName=puzzlet.agentmark)\n\n### 2. FileLoader\n\nRun AgentMark files from your file system. Below is a sample implementation using the Vercel adapter to generate an object:\n\n```ts\nimport { VercelAdapter, VercelModelRegistry, FileLoader, createAgentMark } from \"../src\";\nimport { generateObject } from 'ai';\nimport { openai } from '@ai-sdk/openai';\n\n// Import/Register any Vercel compatible models\nconst modelRegistry = new VercelModelRegistry();\nmodelRegistry.registerModel(['gpt-4o', 'gpt-4o-mini'], (name: string, options: any) =\u003e {\n  return openai(name);\n});\n\n// Specify a file loader + vercel adapter\nconst fileLoader = new FileLoader('./puzzlet/templates');\nconst adapter = new VercelAdapter(modelRegistry);\nconst agentMark = createAgentMark({\n  loader: fileLoader,\n  adapter,\n});\n\nconst prompt = await agentMark.loadObjectPrompt('test/math2.prompt.mdx');\nconst props = {\n  num1: 2,\n  num2: 3,\n};\n\n// Adapt to the Vercel SDK\nconst vercelInput = await prompt.format(props);\n// Call the Vercel SDK directly\nconst result2 = await generateObject(vercelInput);\nconsole.log(result2.object);\n```\n\n### 3. Puzzlet Integration\n\nPuzzlet is a platform for managing, versioning, and monitoring your LLM prompts in production, with built-in observability, evaluations, prompt management, alerts, and more. \n\n```ts\n// Specify the puzzlet loader instead of file loader\nconst puzzletLoader = new PuzzletLoader({\n  apiKey: process.env.PUZZLET_API_KEY!,\n  appId: process.env.PUZZLET_APP_ID!,\n  baseUrl: process.env.PUZZLET_BASE_URL!,\n});\n\nconst agentMark = createAgentMark({\n  loader: puzzletLoader,\n  // rest stays the same...\n});\n```\n\n## Type Safety\n\nAgentMark \u0026 Puzzlet supports automatic type generation from your prompt schemas. Define input (`input_schema`) and output (`schema`) types in your prompt files:\n\n```mdx\n---\nname: math-addition\nmodel:\n  name: gpt-4o\n  schema:\n    type: \"object\"\n    properties:\n      sum:\n        type: \"number\"\n        description: \"The sum of the two numbers\"\n    required: [\"sum\"]\ninput_schema:\n  type: \"object\"\n  properties:\n    num1:\n      type: \"number\"\n      description: \"First number to add\"\n    num2:\n      type: \"number\"\n      description: \"Second number to add\"\n  required: [\"num1\", \"num2\"]\n---\n\n\u003cSystem\u003eYou are a helpful math assistant that performs addition.\u003c/System\u003e\n```\n\nThen generate types using the CLI:\n\n```bash\n# From local files\nnpx @puzzlet/cli generate-types --root-dir ./prompts \u003e puzzlet.types.ts\n\n# From local Puzzlet server\nnpx @puzzlet/cli generate-types --local 9002 \u003e puzzlet.types.ts\n```\n\nUse the generated types with FileLoader:\n\n```ts\nimport { VercelAdapter, VercelModelRegistry, FileLoader, createAgentMark } from \"../src\";\nimport { generateObject } from 'ai';\nimport { openai } from '@ai-sdk/openai';\nimport PuzzletTypes from './puzzlet.types';\n\nconst modelRegistry = new VercelModelRegistry();\nmodelRegistry.registerModel(['gpt-4o', 'gpt-4o-mini'], (name: string, options: any) =\u003e {\n  return openai(name);\n});\n\n// Add the puzzlet types\nconst fileLoader = new FileLoader\u003cPuzzletTypes\u003e('./puzzlet/templates');\nconst adapter = new VercelAdapter\u003cPuzzletTypes\u003e(modelRegistry);\nconst agentMark = createAgentMark({\n  loader: fileLoader,\n  adapter,\n});\nconst prompt = await agentMark.loadObjectPrompt('test/math2.prompt.mdx');\nconst props = {\n  num1: 2,\n  num2: 3,\n};\n\nconst vercelInput = await prompt.format(props);\nconst result2 = await generateObject(vercelInput);\nconsole.log(result2.object.sum);\n```\n\nOr with Puzzlet:\n\n```ts\n// ...\nconst puzzletLoader = new PuzzletLoader\u003cPuzzletTypes\u003e({\n  apiKey: process.env.PUZZLET_API_KEY!,\n  appId: process.env.PUZZLET_APP_ID!,\n  baseUrl: process.env.PUZZLET_BASE_URL!,\n});\n// Rest stays the same...\n```\n\nAgentMark is also type-safe within markdown files. Read more [here](https://puzzlet-ai.github.io/templatedx/docs/type-safety).\n\n## Contributing\n\nWe welcome contributions! Please check out our [contribution guidelines](https://github.com/puzzlet-ai/agentmark/blob/main/CONTRIBUTING.md) for more information.\n\n## Community\n\nJoin our community to collaborate, ask questions, and stay updated:\n\n- [Discord](https://discord.gg/P2NeMDtXar)\n- [Issues](https://github.com/puzzlet-ai/agentmark/issues)\n- [Discussions](https://github.com/puzzlet-ai/agentmark/discussions)\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/puzzlet-ai/agentmark/blob/main/LICENSE).","funding_links":[],"categories":["LLMOps","Orchestration"],"sub_categories":["Observability","Agent Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuzzlet-ai%2Fagentmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuzzlet-ai%2Fagentmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuzzlet-ai%2Fagentmark/lists"}