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 library supports Pydantic AI >=2.27.1,<2.28; the repository lockfile pins the exact CI/runtime version.

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
• Selectable standard Workspace, Todo, Web Fetch, and Shell toolsets
• 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
• Optional EventSink / JSONL event output without coupling Runtime to a backend

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,
    RuntimeAgent,
    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)

    # UI/channel integrations must use the governed facade rather than
    # calling ``compiled.agent`` directly.
    runtime_agent = RuntimeAgent(compiled, channel="example")
    result = await runtime_agent.run("Add 37 and 58.")
    print(result.output)


asyncio.run(main())

Standard tools

Core 0.2 ships standard agent-facing tool contracts while trusted applications retain control of workspace and process authority. Configure backends once, register the plugins, then select them in the Agent Spec:

from agentic_core import (
    CallableShellBackend,
    CallableWorkspaceBackend,
    PluginRegistry,
    StandardToolRuntime,
    register_standard_tool_plugins,
)

runtime = StandardToolRuntime(
    workspace=CallableWorkspaceBackend(
        read_file_fn=read_file,
        glob_fn=glob,
        grep_fn=grep,
        write_file_fn=write_file,
        edit_file_fn=edit_file,
    ),
    shell=CallableShellBackend(
        run_shell_fn=run_shell,
        read_background_shell_fn=read_background_shell,
        list_background_shells_fn=list_background_shells,
        kill_background_shell_fn=kill_background_shell,
    ),
)
plugins = register_standard_tool_plugins(PluginRegistry(), runtime=runtime)

Available plugin ids are core.workspace.standard, core.todo, core.web.fetch, and core.shell.standard. Merely registering them does not enable them; the Agent Spec must select each toolset. Workspace and Shell selection fails during compilation when the corresponding trusted backend is absent.

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 package supports a tested Pydantic AI compatibility window of >=2.27.1,<2.28. Consumers should pin their application lockfile and verify the selected version in CI while the project is below 1.0.

The filesystem Agent store and Debug UI are local reference implementations: they use process-local locks and are intended for one process at a time. Use a database-backed store and authenticated control plane for multi-process or multi-tenant deployments. Debug UI API requests require the random token shown in the startup URL; it remains loopback-only and is not a production control plane.

AgentRuntime.run supports idempotency keys. stream_events is a live event stream and intentionally has no idempotency-key contract; use run or a durable event sink when retry/replay semantics are required.

For Pydantic AI UI and channel protocols, use RuntimeAgent. It preserves the native run_stream_events event contract while routing execution through AgentRuntime for timeout, cancellation, concurrency, Scope, usage, and error normalization. Application code should not call compiled.agent.run(...) directly.

Spec inheritance merges mappings recursively but replaces list/tuple fields with the child value. A child toolsets list therefore replaces, rather than appends to, the parent list.

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