AgentFn.Sdk 0.3.0

AgentFn .NET SDK

The .NET SDK exposes the Credential Client integration path: list the current caller's authorized published Skills, create a Task, query one Task's status/result, separately page its internal Runtime steps, and wait for a terminal result. It owns its small public DTO surface and does not depend on the full platform Contract assembly.

using AgentFn.Sdk;
using System.Text.Json;

using var client = new AgentFnClient(new AgentFnClientOptions
{
    ClientId = clientId,
    PrivateJwks = File.ReadAllText("agentfn-client.private.jwks.json"),
    Scopes = ["skill:read", "skill:run", "task:read"]
});

var skills = await client.ListSkillsAsync();
var skill = skills.Items[0];
var version = skill.PublishedVersionDetails.Single(
    candidate => candidate.Version == skill.LatestVersion);
var created = await client.CreateTaskAsync(new CreateTaskRequest
{
    Skill = $"{skill.SkillId}@{version.Version}",
    Model = "openai/gpt-5",
    Input = "Investigate the incident",
    ReasoningEffort = "high",
    ExtraBody = JsonSerializer.SerializeToElement(new
    {
        chat_template_kwargs = new { enable_thinking = true }
    })
});
var result = await client.WaitForTaskAsync(created.TaskId, timeout: TimeSpan.FromMinutes(2));
var steps = await client.GetTaskRuntimeStepsAsync(created.TaskId);

AgentFnClientOptions.BaseUri defaults to AgentFnClientOptions.DefaultBaseUri (https://agentfn.io-vii.com). Set BaseUri only when targeting another deployment.

ListSkillsAsync calls the existing authorized ListSkills operation. With a Credential Client token, it returns only Skills explicitly allowed for that Client and only their published versions; every PublishedVersionDetails item carries that exact version's OutputSchema and visibility. Inspect and invoke the same version. skill:read is required. GetTaskAsync returns one Task's status/result without internal trace data. GetTaskRuntimeStepsAsync returns { TaskId, Items, NextOffset }; request subsequent pages with NextOffset until it is null. The SDK has no generic RPC client property and does not expose Skill search/publication, Provider or credential management, task-list, cancellation, or other control-plane operations.

Task creation uses the same compact references as the CLI: Skill must be NAME@VERSION, and Model must be PROVIDER/MODEL. Model names may themselves contain /; the first slash separates the Provider.

CreateTaskRequest.ReasoningEffort optionally applies a Provider-supported value to every model call. CreateTaskRequest.ExtraBody is an optional non-secret JSON object up to 64 KiB; its properties are added directly to each request body. AgentFn-controlled model, messages, streaming, tools, tool choice, response format, and reasoning-effort fields cannot be overridden. Retry reuses the original values from the encrypted retry payload.

CreateTaskRequest.IdempotencyKey is opaque, scoped to the authenticated subject, and limited to 200 characters without surrounding whitespace or control characters. Reusing it returns the original Task and does not start another Runtime, even if a later request body differs.

Retry a Failed, Cancelled, or TimedOut Task with await client.RetryTaskAsync(new RetryTaskRequest { TaskId = created.TaskId }); Succeeded and active Tasks are not eligible. The response keeps the same Task ID and advances CurrentAttemptNumber; retry is rejected at or after the fixed RetryExpiresAtUtc, seven days after original creation. GetTaskAsync always returns the latest Attempt projection, while Runtime steps identify their AttemptNumber.

Provision durable model BYOK for a Credential Client separately through the AgentFn control plane or agentfn-cli clients provider-tokens; it is not an SDK management operation. CreateTaskRequest.SessionSecrets remains available for one-shot business Task Secrets; set TaskSecretInput.Strict for values of at least eight characters with no surrounding whitespace that require exact, length-preserving Runtime redaction. AgentFn requires the Client's own Provider Token for model access and never uses an Owner or Developer's personal Token.

Credential Clients authenticate only with private_key_jwt. Configure exactly one of PrivateJwks or ClientAssertionProvider. PrivateJwks accepts a private JWKS document; the SDK loads every RS256-compatible private RSA key and randomly selects one for each fresh assertion. Each key uses its JWK kid, or its RFC 7638 thumbprint when kid is absent. A custom IAgentFnClientAssertionProvider receives the Client ID and exact Token Endpoint and returns a fresh signed assertion, which makes KMS/HSM-backed signing possible. PEM input and explicit key selection are not part of the SDK API; convert PEM material to private JWKS before configuration. The console generates a three-key private JWKS and matching public JWKS when no public JWKS is supplied; the private document is returned exactly once. The SDK neither persists the private material nor exposes Dynamic Client Registration.

The reusable authentication surface is public: IAgentFnClientAssertionProvider, RsaPrivateKeyClientAssertionProvider, IAgentFnAccessTokenProvider, StaticAccessTokenProvider, and ClientAssertionAccessTokenProvider. Use RsaPrivateKeyClientAssertionProvider.FromJwks(...) when an independently constructed assertion provider is useful. JSON-RPC/OAuth wire envelopes and token-cache records remain internal implementation details.

The Credential Client's Owner or a Developer must also add every callable Skill to the Client's allowed-Skill list in the control plane. OAuth scopes and that explicit authorization are both required; skill:run alone does not authorize a public Skill.