{"_id":"@agents-eco/open-agentic-framework","_rev":"2-2c3b49975e00f30b56060cb7195efec0","name":"@agents-eco/open-agentic-framework","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agents-eco/open-agentic-framework","version":"0.1.0","keywords":["agents","ai","llm","agentic","framework","skills","markdown","agents-eco","open-source"],"author":{"name":"agents.eco"},"license":"MIT","_id":"@agents-eco/open-agentic-framework@0.1.0","maintainers":[{"name":"dudenpc","email":"ramankrishna10@gmail.com"}],"homepage":"https://agents.eco","bugs":{"url":"https://github.com/agents-eco/open-agentic-framework/issues"},"bin":{"agents-eco":"dist/cli.js"},"dist":{"shasum":"08ae427c749f79533500493334199815cd1fdb13","tarball":"https://registry.npmjs.org/@agents-eco/open-agentic-framework/-/open-agentic-framework-0.1.0.tgz","fileCount":35,"integrity":"sha512-Scqcck2WwWmuHwy8wo6h0L6QsD7VW3/mA1hp318Rg1Wc4r0ILABEMIdb7wX+iQ/b/C6pfHsfKwVf4adA4Sg6Nw==","signatures":[{"sig":"MEUCIQDP0VlNW9t/sWS3EF/4nKOMfjW4uNhC2aBLxhIKnXwuVQIgbelizY4gOczZHOgHnUfGEDFnWZL+XufMQtw35kFXK+o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":311007},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a3766b6d2aa034a9de3216ac767b8a49ea1a28ee","scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist"},"_npmUser":{"name":"dudenpc","email":"ramankrishna10@gmail.com"},"repository":{"url":"git+https://github.com/agents-eco/open-agentic-framework.git","type":"git"},"_npmVersion":"11.6.2","description":"Open agentic framework — skills-as-markdown, pluggable LLM providers, file-based memory. Built for agents.eco.","directories":{},"_nodeVersion":"25.2.0","dependencies":{"yaml":"^2.3.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/open-agentic-framework_0.1.0_1771388432031_0.7642238219834385","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Moved to @bottensor/framework. Run: npm install @bottensor/framework"}},"time":{"created":"2026-02-18T04:20:31.956Z","modified":"2026-03-28T01:36:59.372Z","0.1.0":"2026-02-18T04:20:32.252Z"},"bugs":{"url":"https://github.com/agents-eco/open-agentic-framework/issues"},"author":{"name":"agents.eco"},"license":"MIT","homepage":"https://agents.eco","keywords":["agents","ai","llm","agentic","framework","skills","markdown","agents-eco","open-source"],"repository":{"url":"git+https://github.com/agents-eco/open-agentic-framework.git","type":"git"},"description":"Open agentic framework — skills-as-markdown, pluggable LLM providers, file-based memory. Built for agents.eco.","maintainers":[{"name":"dudenpc","email":"ramankrishna10@gmail.com"}],"readme":"<p align=\"center\">\n  <img src=\"icon.png\" alt=\"Open Agentic Framework\" width=\"160\" />\n</p>\n\n<h1 align=\"center\">Open Agentic Framework</h1>\n\n<p align=\"center\">\n  <strong>Skills-as-markdown. Pluggable LLM providers. File-based memory.</strong><br/>\n  Built by <a href=\"https://agents.eco\">agents.eco</a> — the decentralized AI agent economy.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@agents-eco/open-agentic-framework\"><img src=\"https://img.shields.io/npm/v/@agents-eco/open-agentic-framework?style=flat-square\" alt=\"npm\" /></a>\n  <a href=\"https://github.com/agents-eco/open-agentic-framework/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" alt=\"MIT License\" /></a>\n  <a href=\"https://github.com/agents-eco/open-agentic-framework\"><img src=\"https://img.shields.io/github/stars/agents-eco/open-agentic-framework?style=flat-square\" alt=\"GitHub stars\" /></a>\n</p>\n\n```\nnpm install @agents-eco/open-agentic-framework\n```\n\n---\n\n## Why This Framework\n\nMost agent frameworks are either too complex or too locked-in. We built this because we needed something that was simple to extend, transparent to debug, and free from vendor dependency.\n\n- **Skills as Markdown** — Extend your agent by writing a `.md` file. No code required. Hot-reloadable, human-readable, agent-authorable.\n- **Pluggable Providers** — OpenAI, Venice, Groq, Ollama, or any OpenAI-compatible API. Swap providers in a single line.\n- **File-Based Memory** — JSONL and Markdown files you can inspect, edit, and version control. No opaque vector databases.\n- **Tool Calling** — Register handlers, define tools in skill frontmatter, full lifecycle hooks at every stage.\n- **Zero Lock-In** — MIT licensed. No vendor dependencies. Works fully offline with Ollama.\n\n## Why agents.eco\n\n[agents.eco](https://agents.eco) is building the decentralized AI agent economy — infrastructure where autonomous agents transact, pay for inference, and operate independently on-chain.\n\nThis framework is the open-source foundation of that vision. We believe the tools agents are built with should be:\n\n- **Open** — Fully readable, forkable, and auditable. MIT licensed.\n- **Composable** — Small, focused primitives that work together. Skills, providers, memory, and tools are all independent and swappable.\n- **Portable** — No dependency on any single provider, cloud service, or platform. Your agent runs wherever you want it to.\n- **Transparent** — Memory stored as files you can read. Billing on-chain. No black boxes.\n\nWhether you use the agents.eco platform or run entirely on your own infrastructure, this framework works the same way.\n\n## Quick Start\n\n### Programmatic\n\n```typescript\nimport { Agent } from \"@agents-eco/open-agentic-framework\";\n\nconst agent = new Agent({\n  name: \"my-agent\",\n  systemPrompt: \"You are a helpful assistant.\",\n  provider: {\n    name: \"venice\",\n    apiKey: process.env.VENICE_API_KEY!,\n    baseUrl: \"https://api.venice.ai/api/v1\",\n    defaultModel: \"qwen3-4b\",\n  },\n});\n\nconst result = await agent.chat(\"What is agents.eco?\");\nconsole.log(result.response);\n```\n\n### CLI\n\n```bash\n# Initialize a new agent project\nnpx @agents-eco/open-agentic-framework init\n\n# Start interactive chat\nnpx @agents-eco/open-agentic-framework chat\n\n# One-shot prompt\nnpx @agents-eco/open-agentic-framework run \"Explain quantum computing in 3 sentences\"\n```\n\n## Providers\n\nWorks with any OpenAI-compatible API out of the box:\n\n```typescript\nimport {\n  veniceProvider,\n  openaiProvider,\n  groqProvider,\n  ollamaProvider,\n  agentsEcoProvider,\n  OpenAIProvider,\n} from \"@agents-eco/open-agentic-framework\";\n\n// Pre-configured providers\nconst venice = veniceProvider(\"your-api-key\");\nconst openai = openaiProvider(\"sk-...\");\nconst groq = groqProvider(\"gsk_...\");\nconst ollama = ollamaProvider(\"llama3.2\"); // local, no API key needed\nconst eco = agentsEcoProvider(\"ak_...\");\n\n// Custom provider\nconst custom = new OpenAIProvider({\n  name: \"my-provider\",\n  apiKey: \"...\",\n  baseUrl: \"https://my-api.com/v1\",\n  defaultModel: \"my-model\",\n});\n```\n\nUse with an agent:\n\n```typescript\nconst agent = new Agent({\n  name: \"my-agent\",\n  systemPrompt: \"You are helpful.\",\n  provider: { name: \"ollama\", baseUrl: \"http://localhost:11434/v1\", defaultModel: \"llama3.2\" },\n});\n\n// Or swap providers at runtime\nagent.useProvider(veniceProvider(\"your-key\"));\n```\n\n## Skills (Markdown-Driven)\n\nSkills are `.md` files with YAML frontmatter. Drop them in a `skills/` directory and the agent loads them automatically.\n\n### Example Skill\n\nCreate `skills/weather.md`:\n\n```markdown\n---\nname: weather\ndescription: Get current weather for a location\ntools:\n  - name: get_weather\n    description: Fetch current weather data\n    parameters:\n      type: object\n      properties:\n        location:\n          type: string\n          description: City name or coordinates\n      required:\n        - location\n---\n\n# Weather Skill\n\nWhen the user asks about weather, use the `get_weather` tool.\nPresent the results in a friendly, conversational format.\nInclude temperature, conditions, and any relevant alerts.\n```\n\n### Register the tool handler:\n\n```typescript\nconst agent = new Agent({\n  name: \"weather-bot\",\n  systemPrompt: \"You help people check the weather.\",\n  provider: { ... },\n  skillsDir: \"./skills\",\n  toolHandlers: {\n    get_weather: async ({ location }) => {\n      const res = await fetch(`https://wttr.in/${location}?format=j1`);\n      const data = await res.json();\n      return JSON.stringify(data.current_condition[0]);\n    },\n  },\n});\n```\n\n### Skill Discovery\n\nSkills are loaded from:\n1. **`skillsDir`** — auto-discovers all `.md` files with YAML frontmatter\n2. **`skills` array** — explicit file paths or `Skill` objects\n3. **Subdirectories** — looks for `SKILL.md` inside each subdirectory\n\n```\nskills/\n├── greeting.md          # Simple skill (single file)\n├── weather.md           # Another simple skill\n├── web-search/\n│   └── SKILL.md         # Skill in a directory (can include extra files)\n└── code-exec/\n    └── SKILL.md\n```\n\n## Memory\n\nFile-based memory that's human-readable and inspectable:\n\n```typescript\nconst agent = new Agent({\n  name: \"my-agent\",\n  systemPrompt: \"You remember previous conversations.\",\n  provider: { ... },\n  memoryDir: \"./.agent/memory\",  // default\n});\n\n// Memory is automatic — conversations are stored after each chat\nawait agent.chat(\"My name is Alice\");\nawait agent.chat(\"What's my name?\"); // \"Your name is Alice\"\n```\n\nMemory files:\n- **`memory.jsonl`** — append-only log (one JSON per line)\n- **`context.md`** — auto-generated markdown summary\n\n### Custom Memory Store\n\n```typescript\nimport { MemoryStore, MemoryEntry } from \"@agents-eco/open-agentic-framework\";\n\nclass MyVectorMemory implements MemoryStore {\n  async add(entry) { /* store in your vector DB */ }\n  async search(query, limit) { /* semantic search */ }\n  async list(limit) { /* return recent entries */ }\n  async clear() { /* wipe */ }\n}\n\nconst agent = new Agent({\n  ...config,\n  memory: new MyVectorMemory(),\n});\n```\n\n### Disable Memory\n\n```typescript\nconst agent = new Agent({ ...config, memory: false });\n```\n\n## Tool Calling\n\nRegister tool handlers that the agent can invoke:\n\n```typescript\nconst agent = new Agent({\n  name: \"tool-agent\",\n  systemPrompt: \"You can use tools to help users.\",\n  provider: { ... },\n  toolHandlers: {\n    calculate: async ({ expression }) => {\n      return String(eval(expression));\n    },\n    fetch_url: async ({ url }) => {\n      const res = await fetch(url);\n      return await res.text();\n    },\n  },\n});\n\n// Or add tools after creation\nagent.tool(\"greet\", async ({ name }) => `Hello, ${name}!`);\n```\n\n## Hooks\n\nIntercept and modify behavior at every stage:\n\n```typescript\nconst agent = new Agent({\n  ...config,\n  hooks: {\n    beforeRequest: async (messages, tools) => {\n      console.log(`Sending ${messages.length} messages`);\n      return messages; // can modify\n    },\n    afterResponse: async (response) => {\n      console.log(`Got response: ${response.content.slice(0, 50)}...`);\n      return response; // can modify\n    },\n    beforeToolCall: async (name, args) => {\n      console.log(`Calling tool: ${name}`, args);\n      return args; // can modify\n    },\n    afterToolCall: async (name, result) => {\n      console.log(`Tool result: ${result.content.slice(0, 50)}...`);\n      return result; // can modify\n    },\n    onError: (error) => {\n      console.error(\"Agent error:\", error);\n    },\n  },\n});\n```\n\n## Configuration (agent.yaml)\n\nThe CLI uses `agent.yaml` for configuration:\n\n```yaml\nname: my-agent\nsystemPrompt: |\n  You are a helpful AI assistant.\n\nprovider:\n  name: venice\n  apiKey: ${VENICE_API_KEY}\n  baseUrl: https://api.venice.ai/api/v1\n  defaultModel: qwen3-4b\n\nskillsDir: ./skills\nmemoryDir: ./.agent/memory\ntemperature: 0.7\nmaxTokens: 4096\n```\n\nEnvironment variables are resolved with `${VAR_NAME}` syntax.\n\n## Integration with agents.eco SDK\n\nUse alongside the [agents-eco-sdk](https://www.npmjs.com/package/agents-eco-sdk) for billing, wallet management, and the full agents.eco platform:\n\n```typescript\nimport { Agent, agentsEcoProvider } from \"@agents-eco/open-agentic-framework\";\nimport { AgentsEco } from \"agents-eco-sdk\";\n\n// Use agents.eco as the LLM provider (pay-per-token with USDC)\nconst agent = new Agent({\n  name: \"eco-agent\",\n  systemPrompt: \"You are powered by agents.eco.\",\n  provider: {\n    name: \"agents.eco\",\n    apiKey: process.env.AGENTS_ECO_API_KEY!,\n    baseUrl: \"https://agents-eco-dfc6baa9f955.herokuapp.com/v1\",\n    defaultModel: \"qwen3-4b\",\n  },\n  skillsDir: \"./skills\",\n});\n\nconst result = await agent.chat(\"Hello!\");\nconsole.log(result.response);\nconsole.log(`Tokens used: ${result.usage.totalTokens}`);\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│                   Agent                      │\n│                                              │\n│  ┌──────────┐  ┌──────────┐  ┌───────────┐ │\n│  │  Skills   │  │  Memory  │  │   Hooks   │ │\n│  │ (SKILL.md)│  │ (JSONL)  │  │           │ │\n│  └─────┬─────┘  └─────┬────┘  └─────┬─────┘ │\n│        │              │              │       │\n│  ┌─────▼──────────────▼──────────────▼─────┐ │\n│  │           Message Builder               │ │\n│  │  system prompt + skills + memory + user  │ │\n│  └─────────────────┬───────────────────────┘ │\n│                    │                         │\n│  ┌─────────────────▼───────────────────────┐ │\n│  │         Provider (OpenAI-compat)        │ │\n│  │  Venice │ OpenAI │ Groq │ Ollama │ ...  │ │\n│  └─────────────────┬───────────────────────┘ │\n│                    │                         │\n│  ┌─────────────────▼───────────────────────┐ │\n│  │           Tool Call Loop                │ │\n│  │  LLM → tool calls → execute → repeat   │ │\n│  └─────────────────────────────────────────┘ │\n└─────────────────────────────────────────────┘\n```\n\n## Built-in Skills\n\nThe package includes starter skills in the `skills/` directory:\n\n| Skill | Description |\n|-------|-------------|\n| `web-search` | Search the web for current information |\n| `code-exec` | Execute JavaScript code snippets |\n| `file-ops` | Read, write, and list files |\n\nCopy them to your project's `skills/` directory and register the corresponding tool handlers.\n\n## API Reference\n\n### `Agent`\n\n| Method | Description |\n|--------|-------------|\n| `chat(message)` | Send a message, get a response (with history + memory) |\n| `run(prompt, systemPrompt?)` | One-shot completion (no history/memory) |\n| `useProvider(provider)` | Swap the LLM provider |\n| `tool(name, handler)` | Register a tool handler |\n| `addSkill(skill)` | Add a skill at runtime |\n| `loadSkillFile(path)` | Load a skill from a file |\n| `getHistory()` | Get conversation history |\n| `clearHistory()` | Clear conversation history |\n| `getMemory()` | Get the memory store |\n\n### `RunResult`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `response` | `string` | The agent's response |\n| `messages` | `ChatMessage[]` | Full message chain |\n| `toolCalls` | `Array<{name, args, result}>` | Tool calls made |\n| `usage` | `{promptTokens, completionTokens, totalTokens, llmCalls}` | Token usage |\n| `duration` | `number` | Time in milliseconds |\n\n## Contributing\n\nWe welcome contributions of all kinds. This project is early and there is significant room to shape its direction.\n\n- **Write a skill** — It is a markdown file. No build step, no boilerplate.\n- **Add a provider** — Implement the `Provider` interface for a new LLM backend.\n- **Improve memory** — Add semantic search, SQLite storage, or vector database adapters.\n- **Report issues** — Bug reports and feature requests help us prioritize.\n- **Submit a pull request** — Code contributions are reviewed promptly.\n\nPlease open an issue before starting large changes so we can align on direction.\n\n## License\n\nMIT — [agents.eco](https://agents.eco)\n\n---\n\n<p align=\"center\">\n  Built by <a href=\"https://agents.eco\">agents.eco</a> — the decentralized AI agent economy.\n</p>\n","readmeFilename":"README.md"}