hypershub-agent-core

hypershub-agent-core is a typed, policy-aware Agent runtime built on Pydantic AI. It provides a stable application boundary around models, prompts, tools, Skills, MCP servers, runtime events, evaluation gates, and release governance.

This is an Alpha release. The agentic.core/v1alpha1 configuration schema and the Python API may change before 1.0. The initial release intentionally pins Pydantic AI 2.27.1 so that runtime behavior is reproducible.

Capabilities

• Strict YAML/JSON Agent specs with deterministic inheritance and fingerprints
• OpenAI-compatible and Anthropic-compatible model registries using lazy secret references
• Explicit plugin registration and policy-gated tool execution
• Filesystem Skills with confined resources, integrity checks, and trusted-source boundaries
• Allowlisted MCP stdio commands and remote endpoint aliases with lazy Bearer authentication
• Stable events, usage accounting, cancellation, idempotency, concurrency, and queue limits
• Agent evaluation suites, repeat baselines, regression diffs, and release gates
• A loopback-only Agent Studio and debug UI for trusted development environments

Requirements

• Python 3.11 or newer
• A supported model endpoint and API credential for live Agent runs
• Trusted application code that defines the allowed plugins, Skills, tools, MCP commands, remote endpoints, and workspace roots

Install

python -m pip install hypershub-agent-core

The distribution name is hypershub-agent-core, the import package is agentic_core, and the CLI command is agentic-core.

Quick start

Create models.yaml. Credentials are references, never plaintext values:

models:
  - id: default
    provider: openai_chat
    model: gpt-4.1-mini
    base_url: https://api.openai.com/v1
    api_key: env://OPENAI_API_KEY

Create agent.yaml:

schema_version: agentic.core/v1alpha1
id: math-agent
name: Math Agent
model:
  ref: default
prompts:
  stable:
    - Use the add_numbers tool for integer addition and return its exact result.
toolsets:
  - plugin: core.arithmetic
run_policy:
  request_limit: 4
  tool_calls_limit: 4
  timeout_seconds: 60

Compile and run it from trusted application code:

import asyncio

from agentic_core import (
    AgentCompiler,
    AgentRuntime,
    ModelRegistry,
    PluginRegistry,
    load_agent_spec,
    register_builtin_plugins,
)


async def main() -> None:
    models = ModelRegistry.from_file("models.yaml")
    plugins = register_builtin_plugins(PluginRegistry())
    spec = load_agent_spec("agent.yaml")
    compiled = AgentCompiler(models=models, plugins=plugins).compile(spec)
    result = await AgentRuntime().run(compiled, "Add 37 and 58.")
    print(result.output)


asyncio.run(main())

Validate configuration without making a model request:

agentic-core models validate models.yaml
agentic-core spec validate agent.yaml
agentic-core spec fingerprint agent.yaml

Security model

This package is a library for trusted application processes; it is not a sandbox. Agent YAML cannot introduce raw MCP URLs or arbitrary executable commands. The application must inject reviewed command aliases, endpoint rules, plugin registries, Skill sources, workspace roots, and approval policy.

Keep provider and MCP credentials in a secret manager or environment variables referenced with env:// or file://. Do not put plaintext secrets in Agent specs, prompts, tool arguments, logs, or evaluation artifacts. See SECURITY.md for reporting and deployment guidance.

Scope and compatibility

The initial package deliberately favors reproducible behavior over dependency flexibility and therefore requires Pydantic AI 2.27.1. Consumers should pin hypershub-agent-core to a compatible minor version while the project is below 1.0.

The bundled arithmetic and guidance plugins demonstrate the plugin contract. Production applications are expected to register their own reviewed plugins and policies. Provider credentials are resolved only when a model is built.

License

MIT